/*
 * Copyright 2011 Mark Davidson.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */

package org.dctmcommons;

import com.documentum.fc.client.IDfACL;
import com.documentum.fc.client.IDfFolder;
import com.documentum.fc.client.IDfSession;
import com.documentum.fc.common.DfException;

/**
 * Fluent interface for building folder paths. Please note that no transactions
 * are used during the operation.
 * @author Mark Davidson
 */
public interface IPathBuilder {

	/**
	 * Adds a path element.
	 * @param name The folder name
	 * @return The IPathBuilder instance.
	 */
	public IPathBuilder add(String name);
	
	/**
	 * Adds a path element.
	 * @param name The folder name
	 * @param type The object type
	 * @return The IPathBuilder instance.
	 */
	public IPathBuilder add(String name, String type);
	
	/**
	 * Adds a path element.
	 * @param name The folder name
	 * @param type The object type
	 * @param acl The ACL
	 * @return The IPathBuilder instance.
	 */
	public IPathBuilder add(String name, String type, IDfACL acl);
	
	/**
	 * Adds a path element.
	 * @param name The folder name
	 * @param acl The ACL
	 * @return The IPathBuilder instance.
	 */
	public IPathBuilder add(String name, IDfACL acl);
	
	/**
	 * Sets the default object type.
	 * @param type The object type
	 * @return The IPathBuilder instance.
	 */
	public IPathBuilder setDefaultType(String type);
	
	/**
	 * Sets the default ACL
	 * @param acl The ACL
	 * @return The IPathBuilder instance.
	 */
	public IPathBuilder setDefaultAcl(IDfACL acl);
	
	/**
	 * Specifies whether the builder should check whether the added folder
	 * elements should be checked (default = true).
	 * @param requiresCheck Whether the folder check should be performed
	 * @return The IPathBuilder instance.
	 */
	public IPathBuilder setCheckTargetFolderExists(boolean requiresCheck);
	
	/**
	 * Specifies whether the builder should check whether the base path should
	 * be checked (default = true).
	 * @param requiresCheck Whether the folder check should be performed
	 * @return The IPathBuilder instance.
	 */
	public IPathBuilder setCheckBasePathExists(boolean requiresCheck);
	
	/**
	 * Builds the path as a series of linked IDFFolders. The build process is
	 * not performed within a transaction. This method should be called last.
	 * @param session The session
	 * @return The array of newly created folders. This does not include folders
	 * that constitute the base path.
	 * @throws DfException The repository exception
	 */
	public IDfFolder[] build(IDfSession session) throws DfException;
}
